<?php

/**
 * Fetches external resources.
 *
 * Implementation is responsible for resolving relative URLs using stored context.
 *
 * Implementation may cache resources locally.
 *
 * ---
 * 
 * Загружает внешние ресурсы.
 *
 * Реализация  должна   уметь  нормализовывать  относительные   URL  с
 * использованием текущего контекста.
 *
 * Реализация может кэшировать загружаемые ресурсы.
 */
interface IResourceLoader {
  /**
   * Fetches an  external resource.   Returns a resource  handle which
   * can be  used to check  resource status (e.g. whether  resource is
   * available) or get resource raw contents.
   * 
   * If  implementation caches resources  locally, this  method should
   * return the same IResource instance when it's called with the same
   * resource URL.
   *
   * Usage example:
   * <code>
   * $style = $loader->load('http://host.com/css/style.css');
   * </code>
   *
   * @param string $resource_url URL of the resource to be fetched.
   *
   * @return IResource handle of the resource.
   *
   * @see IResource
   *
   * ---
   *
   * Загружает внешний  ресурс. Возвращает описатель  ресурса, который
   * содержит  данные о  состоянии  ресурса (в  частности,  был ли  он
   * доступен) и может быть использован для доступа к его содержимому.
   *
   * Если  реализация кэширует ресурсы,  этот метод  должен возвращать
   * один и тот же объект IResoure при вызове с одним и тем же URL.
   *
   * Пример использования:
   * <code>
   * $style = $loader->load('http://host.com/css/style.css');
   * </code>
   *
   * @param string $resource_url URL загружаемого ресурса.
   *
   * @return IResource описатель загруженного ресурса.
   *
   * @see IResource
   */
  function load($resource_url);

  /**
   * Adds a new URL to be used for resolving relative resource URLs to
   * the stack.
   *
   * Implementation should allow $context to be relative URL.  Is this
   * case,  it should  be  converted to  absolute  form using  current
   * loader context.
   *
   * Example:
   * <code>
   * $loader->pushContext('http://host.com/');
   * $loader->load('sample.gif'); // Loads http://host.com/sample.gif
   * $loader->pushContext('./sub/dir');
   * $loader->load('sample.jpg'); // Loads http://host.com/sub/dir/sample.gif
   * $loader->popContext();
   * $loader->load('sample.png'); // Loads http://host.com/sample.ong
   * </code>
   *
   * @param string $content context URL
   *
   * ---
   * 
   * Добавляем новый URL,  который будет использовать для нормализации
   * относительных URL ресурсов, на вершину стека.
   *
   * Реализация  должна  позволять   передавать  в  качестве  $context
   * относительный URL.  В этом  случае, он должен быть нормализован с
   * использованием текущего контекста.
   *
   * Пример:
   * <code>
   * $loader->pushContext('http://host.com/');
   * $loader->load('sample.gif'); // Loads http://host.com/sample.gif
   * $loader->pushContext('./sub/dir');
   * $loader->load('sample.jpg'); // Loads http://host.com/sub/dir/sample.gif
   * $loader->popContext();
   * $loader->load('sample.png'); // Loads http://host.com/sample.ong
   * </code>
   *
   * @param string $content новый базовый URL
   *
   */
  function pushContext($context);

  /**
   * Returns to the previously saved base URL.
   * 
   * @throw  ExceptionMissingResourceLoaderContext when  popContext is
   * called without corresponding pushContext call.
   *
   * ---
   *
   * Возврашается к ранее сохранённому базовому URL
   *
   * Выбрасывает  ExceptionMissingResourceLoaderContext в  том случае,
   * если popContext вызывается без соответствующего ему pushContext.
   */
  function popContext();
}

?>